fix(native): narrow a var()-valued font-family to its first family - #417

Problem

React Native's fontFamily takes one family, not a stack. Three compiler paths produce it and only two narrowed:

• parseFontFamily — the typed path, took value[0].
• parseFont — the font shorthand, took value.family[0].
• parseUnparsed — everything LightningCSS cannot type, returned the token list as it found it.

That third path is not exotic. Every var()-valued font-family goes down it, which is how Tailwind emits font-sans / font-serif / font-mono, and so does plain CSS the parser rejects:

font-family: Inter, Helvetica,;      ->  fontFamily: ["Inter","Helvetica"]
font-family: ,Inter, Helvetica;      ->  fontFamily: ["Inter","Helvetica"]
font-family: Inter,,Helvetica;       ->  fontFamily: ["Inter","Helvetica"]
font-family: "Inter", "Helvetica",;  ->  fontFamily: ["Inter","Helvetica"]
font-family: 12, Inter;              ->  fontFamily: [12,"Inter"]
font-family: ,;                      ->  fontFamily: []

@keyframes takes the same path, so an animation carried the array too. TextStyle.fontFamily is a string, so Fabric refuses every one of them: no font change, no warning, the element renders in the platform default.

None of it can be caught downstream — applyDeclarations copies a static style onto the props with Object.assign, never through applyValue.

Those three are the producers of a font-family-keyed value. There is a fourth route that produces a font-keyed one, which neither plane narrows and this PR does not change; it is the last entry under Known limits.

Fix

The reduction exists once, in src/utilities/font-family.ts, and the three producers read it. It is flatten-then-first-usable rather than take-the-first: a nested group is read in place, and an entry that cannot name a family — a number, a null, an empty group — is skipped, the way a browser skips a family it cannot use. A stack with nothing usable emits no declaration at all, so a family set by a lower-specificity rule survives the cascade instead of being overwritten with [].

The reduction has no opinion about generic keywords, and that is deliberate. font-family: sans-serif, Inter narrows to "sans-serif", because the first entry is usable as a family name and a browser resolves it the same way — a generic is always available, so nothing behind it is ever reached. Measured identical on main and this branch; it is stated here only because it was nowhere stated before.

The one answer the compiler cannot give is deferred: the first usable entry is a var(), whose value only exists at render. That descriptor is emitted whole and reduced again in applyValue, the first place on that path where the property name and the resolved value are both in hand. A var() standing behind a literal is narrowed away at compile time, because React Native can never reach it — which also drops the declaration's reactivity, since its value can no longer change.

One nuance on that runtime half, measured rather than assumed. When a resolved value yields nothing usable, applyValue declines to set the key — but it cannot preserve a family an earlier rule put there, because applyDeclarations runs delete target[prop] before it resolves. Under .b { font-family: Georgia } followed by .a { font-family: var(--n) } over --n: 12, this branch produces {} and main produces { fontFamily: 12 }: better either way, since 12 is a value React Native refuses, but Georgia is gone in both. The cascade genuinely does survive on the compile-time path, where no descriptor is emitted at all — the same pair written .a { font-family: ,; } keeps Georgia on this branch and yields [] on main. The source comment at that branch says which of the two it is claiming.

Two supporting fixes fall out:

• isStyleFunction asked only whether index 0 was typeof "object" with no own keys, so [[], "Arial"] read as a function call (Object.keys([]) is empty too) and [null, "Arial"] threw Cannot convert undefined or null to object. Both shapes occur in a resolved stack.
• applyValue's previous first-then-descend loop set a raw null on fontFamily ten lines below the comment explaining that null means "set to undefined", and set fontFamily: 12 for --n: 12; font-family: var(--n).

Values, before and after

Measured by rendering each stylesheet through registerCSS + render on this branch and on main:

Every main cell is a value React Native refuses.

Tests

62 cases across four planes — the reduction on its own, the compiler, applyValue, and a real render. 41 of them fail on upstream/main with this branch's source reverted; 21 pass, and each one says in a comment why it is a deliberate control rather than a guard. I measured that per test rather than assuming it: the seven tests this PR opened with turned out to be five controls and two guards, which is what prompted the rest of this work.

The measurement is reproducible: put all five source files back to f70c402 byte-exactly, keep every test, and run the six files this PR touches. That reports Tests: 41 failed, 117 passed, 158 total with numRuntimeErrorTestSuites 0 — no suite fails to load. The 158 is the six files in full; 96 of them are typography.test.tsx's pre-existing utilities, which leaves the 62 this PR adds.

Nine of the 41 are the new unit's own file, which fails with narrowFontFamily is not a function once src/utilities/font-family.ts is gone. That is what a missing module looks like rather than a value difference, so the honest figure is 32 of the 62 red for a real difference in what React Native is handed, and 9 more that exist only because the unit does.

The native plane carries the cases no compiler assertion can reach. Every var() spelling below compiles to the same deferred descriptor whatever the variable holds, so only a render says which family lands:

• a var() holding a multi-family stack
• an undefined var() with a literal fallback in its own parentheses, and one whose fallback is itself a stack
• a nested var(--a, var(--b, serif)), both with and without --b defined
• a fallback in the head of a stack, with a family behind it
• quoted family names containing spaces, and containing commas
• an unusable head inside the resolved stack (12, unset, an empty group)
• a stack supplied at render through <VariableContextProvider />, and its update on rerender

Every var() fixture declares its variable twice on purpose. A single-definition variable is inlined at compile time and narrowed there, which makes the runtime path unreachable from a naively written fixture.

src/__tests__/vendor/tailwind/typography.test.tsx gains the Font Family block the file was missing. The four default-theme cases are controls — ui-sans-serif is a CSS generic no typeface is registered under, so narrowing makes the value type-correct without changing what is drawn. Both overridden---font-sans cases bind, and only one of them reaches a real family: the :root override resolves Georgia, while the .dark override is not active and resolves the theme's own ui-sans-serif — the same generic as the four controls, with no face behind it either. It binds anyway, because a second definition defeats the inliner and on main that generic arrives as the whole seven-entry stack rather than as a string.

Mutation-proved, one broken thing at a time, counting reddened cases across the six test files this PR touches:

The in-scope column understates one row. Unscoping the runtime reduction from fontFamily reddens 13 cases in these six files but 134 across 19 files repo-wide, because every array-valued property then goes through the reduction — box-shadow, filter, transform, safe-area and the rest. That whole-repo figure is the one worth reading; the prop === "fontFamily" guard is load-bearing far outside this feature.

The last two rows are reported rather than hidden, and they are the same finding twice. Both typed producers hand the reduction a string[]: parseFontFamily a value and parseFont a value.family. For any array of strings narrowFontFamily returns the first element when there is one and nothing when there is not, which is exactly what [0] returns — so the two spellings are equivalent on every input the type permits and no test can distinguish them. I checked the second one repo-wide as well as in scope, and it reddens nothing there either. Both blocks guard the paths staying attached to the shared reduction, not a behaviour change, and their comments say exactly that.

Known limits

An unquoted multi-word family name behind a var() loses its tail. reduceParseUnparsed groups an unparsed value by comma and nests a multi-token group, so for font-family a one-entry stack of two idents and a two-entry stack of one ident each collapse onto the identical array:

--f: Helvetica Neue    ->  ["f", ["Helvetica", "Neue"]]
--f: Inter, Helvetica  ->  ["f", ["Inter", "Helvetica"]]

Nothing downstream can separate them, so the reduction reads both as a stack and --f: Helvetica Neue renders as Helvetica. Quoting the name keeps it a single string (["f", "Helvetica Neue"]) and it renders whole, which is CSS's own answer for a family name that is not one ident. The typed path is unaffected — LightningCSS joins the idents there, and this PR pins that both paths agree on the quoted spelling.

I left it rather than picking a reading: joining a nested group instead would fix this case and break var(--x, A, B), C, whose fallback nests the same way and does mean a comma list. A real fix separates the two groupings in reduceParseUnparsed, which is a shared parser change touching every property. Both halves of the limit are pinned — the identical compiled value on the compiler plane, the resulting family on the native plane — and the mutation table's space-group row shows that lifting it reddens exactly those two and nothing else.

vars() cannot express a font stack under tsc, though it now works at runtime. The behaviour half is closed: vars({ "--stack": ["Inter","Helvetica"] }) renders fontFamily: "Inter" on this branch and hands React Native the array on main. The types are the part that is still shut, on the deprecated API, in two independent places:

• react-native-css/runtime type-resolves to src/runtime.ts → src/web/api.tsx, whose vars is Record<string, string | number>. A stack is TS2322: Type 'string[]' is not assignable to type 'string | number'. Jest resolves the same specifier to src/runtime.native.ts and runs the native function, so the mismatch is invisible at runtime.
• the native vars() return type is not assignable to a style prop at all: TS2769 … Type '{ [VAR_SYMBOL]: string; } & { [k: string]: StyleDescriptor; }' is not assignable to type 'StyleProp<ViewStyle>'.

Both are types-only defects on vars() itself rather than anything this change touches, so the equivalent runtime coverage is written through <VariableContextProvider /> — the API vars() is deprecated in favour of — which typechecks and exercises the identical path.

A null head cannot reach the reduction through a render. applyValue handles [null, "Arial"] and a unit test pins it, but StyleDescriptor has no null member so the value does not compile, and resolveValue's own isDescriptorArray reads a null head as a style-function call (typeof null === "object") and resolves the stack away before applyValue sees it. That predicate is the same defect isStyleFunction had, on a shared path used by every property; fixing it there is a separate change. The native-plane test states the measurement and asserts the head the type system does allow.

font: 12px var(--stack) is narrowed by neither plane. The font shorthand with a var() inside it cannot be typed by LightningCSS either, so it takes the unparsed path — but with property === "font", which the compiler's narrowing misses because that is keyed on font-family, and which applyValue misses because its guard is prop === "fontFamily". Measured identical on main and on this branch:

:root { --stack: Inter, Helvetica; }
.other { --stack: Georgia, serif; }
.a { font: 12px var(--stack); }   ->  { "font": [12, ["Inter","Helvetica"]] }

React Native has no font style prop, so nothing consumes that value on either side and this is pre-existing rather than a regression. I am naming it because it is a fourth route to the same shape, and the framing at the top — three producers, two of which narrowed — does not account for it. Closing it properly means the unparsed path understanding that font decomposes into font-family and friends, rather than a second property name added to two guards; that is a larger change than this one and I would rather not smuggle it in here.

One thing to flag

src/utilities/index.ts gains export * from "./font-family", and ./utilities is an already-published subpath, so narrowFontFamily and the FontFamilyNarrowing union become supported API on merge. Nothing marks them internal. That matches how isStyleFunction and Specificity are already exported from the same subpath, so I have assumed it is intended — say the word and I will move the module somewhere unexported instead. Relatedly, isStyleFunction's parameter widens from StyleDescriptor to unknown: source-compatible for every caller, but it does change the exported .d.ts and removes some compile-time pressure on them.

Second commit — the sibling predicate had the same hole

isStyleFunction is not alone in that file. isStyleDescriptorArray sits six lines above it, asks the same question from the other side — is this a list of VALUES rather than a function to evaluate — and carried the identical untreated typeof value[0] === "object".

Its failure is quieter than the throw, which is why it outlived it. typeof null is "object", so a null head sends it into the branch that demands an array, and it answers false for a value that IS a descriptor array:

isStyleDescriptorArray([null, "Arial"])   before: false      after: true
isStyleDescriptorArray(["Inter", "Arial"]) before: true      after: true    (control)
isStyleDescriptorArray([{}, "var"])        before: false     after: false   (control)
isStyleDescriptorArray([["Inter"], "Arial"]) before: true    after: true    (control)

Null is not a function head. It is a value — a hole left where an operand could not be parsed — and it reaches a native runtime as null rather than undefined because the sheet goes through JSON.stringify on the way. The predicate is exported and read at ten call sites across dimension, filters, transform-functions, box-shadow, _expand and variables, so the misclassification is not local to one caller.

Both functions are now the same shape for the same stated reason, and src/__tests__/utilities/style-descriptor.test.ts gains a describe for the sibling mirroring the one it already had: three controls that pass before and after, and the null case that does not.

Fixing one copy and leaving its twin would have made this pull request a partial fix of one defect.

Verification

Windows, warm cache, run twice with identical results:

Test Suites: 2 failed, 4 skipped, 58 passed, 60 of 64 total
Tests:       3 failed, 21 skipped, 1114 passed, 1138 total

Zero suite-load failures, verified from --json rather than from the summary line: numRuntimeErrorTestSuites 0, numTotalTests 1138, and the two failing suites account for all 3 failures inside their own assertions. Those three are src/__tests__/babel/{react-native,react-native-web}.test.ts, a pre-existing Windows-only babel-plugin-tester output mismatch over an unrewritten relative require("../View"); they fail identically on pristine main on the same machine. yarn typecheck and yarn lint both exit 0.